HybridMail Technical

CustomData XML attachment

The customData attachment is used collect and store various properties of a letter which do not directly relate to its addressing and delivery, so that they can be included in reports. Typical examples of such data might be: an account number, order number, cost-code, letter-category etc.

Schema

<mkzAttachment type="customData">
	<onSubmit>
		<customData [scan|identifier]  [dateFormat="yyyyMMdd"] 
					[property="prop-name"] [metadata="meta-name"]
					field="ff" | multiField="ff,gg,hh..."  [parse="split-chars"] >default-text
		</customData>
		<letterName [scan|identifier] [property="name"] [field="ff"] />
		<letterStream [scan|identifier] [property="name"] [field="ff"] />
	</onSubmit>

	<onRelease> 
		<loadCustomData/>	
	</onRelease> 	
</mkzAttachment>

The XML can only be executed during the OnSubmit phases.

The XML supports the following elements during OnSubmit. There can be multiple instances of any of these.

<customData> Define the specified customData field and link it to the letter.

This element defines a custom data field that will be associated with the letter. There may be up to 10 instances of this element, each with a different field value.

The field="ff" attribute specifies which custom data field will be defined. ff can be between 1 and 10 (inclusive).

The multiField="ff,gg,hh,...,kk,ll" attribute defines which custom data fields will be created. ff,gg,hh etc. are numbers from 1 to 10 (inclusive). They can be in any order but each number must only appear once.

N.B. It is mandatory to specify one of field or multiField (but not both).

The parse="split-chars" attribute is only applicable if the multiField attribute is specified. it defines a set of characters used to split the scanned text into the multi-fields.

E.g. if parse="/\" then the scanned text would be split at each occurrence of '/' or '\'.
Therefore, if the scanned text is "fred/harry/george\bill" then the split multi-fields would be "fred", "harry", "george", "bill".

If parse is not specified, the default split characters are ',' and ';'.
This attribute is optional and only applicable to multiField

The property="prop-name" attribute can be used instead of scan|identifier and defines which custom property of the submitted PDF file will be written into the custom data field. N.B. it is the value of the property whose name is "prop-name" (case-sensitive) that will be written into the custom data field. If the property does not exist, or its value is empty, no custom data field is created; i.e. there is no default value.

The metadata="meta-name" attribute writes the value of the current customData field to the letter PDF file metadata as an entry named "ff-name" where 'ff' is the number from the field attribute.

E.g. If the scanned text was "george" then the attributes field="3" metadata="wizardName" would write the metadata entry
"3-wizardName = george" to the PDF file.

The dateFormat="format-string" attribute is only applicable if the scanned text is a valid date. If this attribute exists, then the scanned text will be converted to the specified date format before being stored as custom data or written as metadata.

E.g. if the scanned text was "Wednesday April 26th 2017" and the attribute dateFormat=="yyyyMMdd" is present, then the string "20170426" would be added as the custom data value.

<letterName> Set the letter name/reference.

This element defines a value that will be associated with the letter. This value differs from customData values in that it is an indexed, searchable value that is typically unique for each letter and that it is displayed in the Website in the lists of mail items e.g. Queued or Posted. The maximum length stored is 100 characters.

The field="ff" attribute specifies which custom data field will be written into the letter name. This field must have already been assigned.

<letterStream> Set the letter name/reference.

This element defines a value that will be associated with the letter. This value differs from customData values in that it is an indexed value that is typically associated with the nature of the system that generated the letter. The maximum length stored is 100 characters.

The field="ff" attribute specifies which custom data field will be written into the letter name. This field must have already been assigned.

Examples

Set a custom data field in various ways.

<!-- use the literal text as CustomDataField1 -->
<customData field="1" >literaltext</customData>

<!-- scan text from letter as CustomDataField2-->
<customData field="2" scan="20,89,70,8"/>

<!-- scan text from letter, as CustomDataField2 but use literal text if scan region empty-->
<customData field="2" scan="20,89,70,8">literaltext</customData>

<!-- scan text from letter and use text following "Patient No:" as CustomDataField2-->
<customData field="2" extract="Patient No:" scan="20,89,70,8"/>

<!-- scan text from letter and use "Patient No:" plus the following text as CustomDataField4,
or use "Patient unknown" if the scanned string is empty-->
<customData field="4" extract="Patient No:" includeRef="1 scan="20,89,70,8"> Patient unknown
</customData>

<!-- scan text from letter, split it on each occurrence of either '/' or '\' 
and store it in the specified customdata fields -->
<customData multiField="4,5,2,6,10" scan="20,89,70,8" parse="/\" />

Scan text from letter, split it on each occurrence of either '/' or '\' and store it in the specified customdata fields.

<customData multiField="4,5,2,6,10" scan="20,89,70,8" parse="/\" />

N.B. When using multiField, if there are insufficient fields scanned from the page then only those scanned are stored. E.g. in the above example if the scanned text is "fred/george" then the scanned multi-fields are "fred" and "george". Therefore customDataField 4 will receive the value "fred" and customDataField 5 will receive the value "george". Other customDataFields will not receive a value.

Scan two areas of the letter, one for the Hospital Number and one for the patient NHS number. The two numbers are placed in separate customData fields, and the letterName is set to the concatenation of the two numbers.

<mkzAttachment type="customData">
	<onSubmit>
		<setIdentifier name="hosp" scan="135,73,56,17" extract="Hospital No:" />
		<setIdentifier name="nhs" scan="135,73,56,17" extract="NHS No:" />
		<customData field="1" identifier="hosp" />
		<customData field="2" identifier="nhs" />
		<setIdentifier name="both" identifier="hosp" >
			<extendIdentifier identifier="nhs" />
		</setIdentifier>
		<letterName identifier="both" />
	</onSubmit>
</mkzAttachment>